<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Hoodoo::Client::AugmentedBase</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/github.css" type="text/css" media="screen" />
<script src="../../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>
    <div class="banner">
        <h1>
            <span class="type">Module</span>
            Hoodoo::Client::AugmentedBase
        </h1>
        <ul class="files">
            <li><a href="../../../files/lib/hoodoo/client/augmented_base_rb.html">lib/hoodoo/client/augmented_base.rb</a></li>
        </ul>
    </div>
    <div id="bodyContent">
        <div id="content">
    <div class="description">
      
<p>Base mixin for <a
href="AugmentedHash.html">Hoodoo::Client::AugmentedHash</a> and <a
href="AugmentedArray.html">Hoodoo::Client::AugmentedArray</a>, used by the
<a href="Endpoint.html">Hoodoo::Client::Endpoint</a> family for return
values in its resource calling API - see:</p>
<ul><li>
<p><a href="Endpoint.html#method-i-list">Hoodoo::Client::Endpoint#list</a></p>
</li><li>
<p><a href="Endpoint.html#method-i-show">Hoodoo::Client::Endpoint#show</a></p>
</li><li>
<p><a href="Endpoint.html#method-i-create">Hoodoo::Client::Endpoint#create</a></p>
</li><li>
<p><a href="Endpoint.html#method-i-update">Hoodoo::Client::Endpoint#update</a></p>
</li><li>
<p><a href="Endpoint.html#method-i-delete">Hoodoo::Client::Endpoint#delete</a></p>
</li></ul>

<p>The error handling mechanism this mixin provides is intentionally analogous
to that used for mapping <a href="../ActiveRecord.html">ActiveRecord</a>
model validation failures to platform errors in <a
href="../ActiveRecord/ErrorMapping.html">Hoodoo::ActiveRecord::ErrorMapping</a>
for when resource endpoint implementations are calling other resource
endpoint implementations, while also supporting use cases of external
callers wanting to communicate with resources from “outside the system”.</p>

    </div>








    <!-- Method ref -->
    <div class="sectiontitle">Methods</div>
    <dl class="methods">
        <dt>A</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-adds_errors_to-3F">adds_errors_to?</a>
              </li>
          </ul>
        </dd>
        <dt>P</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-platform_errors">platform_errors</a>
              </li>
          </ul>
        </dd>
        <dt>S</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-set_platform_errors">set_platform_errors</a>
              </li>
          </ul>
        </dd>
    </dl>








      <!-- Section attributes -->
      <div class="sectiontitle">Attributes</div>
      <table border='0' cellpadding='5'>
          <tr valign='top' id='attribute-i-response_options'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>response_options</td>
            <td class='attr-desc'><p>On success, this Hash may be updated with options describing
&#39;out-of-band&#39; information associated with the response, derived
from HTTP headers for HTTP-based transports. Non-HTTP transports still
carry HTTP-like headers and apply equally here.</p>

<p>For more about the mapping from header to option, see class method <a
href="Headers.html#method-c-x_header_to_options">Hoodoo::Client::Headers.x_header_to_options</a>.
Since <a href="../../Hoodoo.html">Hoodoo</a> itself sets up
<code>X-Interaction-ID</code> and <code>X-Service-Response-Time</code>
headers in <em>most</em> cases, you can expect to at least find the options
<code>interaction_id</code> and <code>service_response_time</code> set for
successful calls.</p>

<p>Under some circustances, especially for certain error conditions, the value
may be <code>nil</code>, though <a href="../../Hoodoo.html">Hoodoo</a>
endeavours to avoid this and at least fill in <code>interaction_id</code>
where possible.</p></td>
          </tr>
      </table>


    <!-- Methods -->
      <div class="sectiontitle">Instance Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-i-adds_errors_to-3F">
              <b>adds_errors_to?</b>( collection )
            <a href="../../../classes/Hoodoo/Client/AugmentedBase.html#method-i-adds_errors_to-3F" name="method-i-adds_errors_to-3F" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>This call is typically used by resource endpoint implementations (“service
authors”) during inter-resource calls, rather than by external entities
calling into a system via <a href="../Client.html">Hoodoo::Client</a>.</p>

<p><a href="../Errors.html">Errors</a> set via <a
href="AugmentedBase.html#method-i-set_platform_errors">set_platform_errors</a>
are added to the given <a href="../Errors.html">Hoodoo::Errors</a>
instance. Generally, <a
href="AugmentedBase.html#method-i-set_platform_errors">set_platform_errors</a>
is only called by the <a href="../Client.html">Hoodoo::Client</a>
under-the-hood implementation code as part of routine error handling.</p>

<p>Returns <code>true</code> if any errors were added else <code>false</code>
if everything is OK (no platform errors have been noted internally).</p>

<p>This makes the idiomatic example for “make inter-resource call, add any
errors to my service&#39;s response and return on error” very simple, at
the expense of modifying the passed-in error collection contents (mutating
a parameter is a risky pattern). For an alternative pattern which avoids
this, see <a
href="AugmentedBase.html#method-i-platform_errors">platform_errors</a>.</p>

<p>Otherwise, a hypothetical resource <code>Member</code> could be listed as
follows, as part of a hypothetical <code>show</code> implementation of some
other resource:</p>

<pre><code>def show( context )
  list = context.resource( :Member ).list()
  return if list.adds_errors_to?( context.response.errors )
  # ...
end
</code></pre>

<p>External callers that have nothing to do with resource endpoint
implementations could still construct an errors collection manually and
make use of this method, but calling <a
href="AugmentedBase.html#method-i-platform_errors">platform_errors</a>
makes a lot more sense for that use case.</p>
<dl class="rdoc-list note-list"><dt><code>collection</code>
<dd>
<p>A <a href="../Errors.html">Hoodoo::Errors</a> instance, typically obtained
from the <a href="../Services/Context.html">Hoodoo::Services::Context</a>
instance passed to a service implementation in calls like <a
href="../Services/Implementation.html#method-i-list">Hoodoo::Services::Implementation#list</a>
or <a
href="../Services/Implementation.html#method-i-show">Hoodoo::Services::Implementation#show</a>,
via <code>context.response.errors</code> (i.e. <a
href="../Services/Context.html#attribute-i-response">Hoodoo::Services::Context#response</a>
/ <a
href="../Services/Response.html#attribute-i-errors">Hoodoo::Services::Response#errors</a>).
The collection you pass is updated with any errors noted internally via
(usually-middleware-automatically-called) method <a
href="AugmentedBase.html#method-i-set_platform_errors">set_platform_errors</a>.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-adds_errors_to-3F_source')" id="l_method-i-adds_errors_to-3F_source">show</a>
              </p>
              <div id="method-i-adds_errors_to-3F_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/augmented_base.rb, line 81</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">adds_errors_to?</span>( <span class="ruby-identifier">collection</span> )
  <span class="ruby-identifier">to_add</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">platform_errors</span>()

  <span class="ruby-keyword">if</span> <span class="ruby-identifier">to_add</span>.<span class="ruby-identifier">has_errors?</span>
    <span class="ruby-identifier">collection</span>.<span class="ruby-identifier">merge!</span>( <span class="ruby-identifier">to_add</span> )
    <span class="ruby-keyword">return</span> <span class="ruby-keyword">true</span>
  <span class="ruby-keyword">else</span>
    <span class="ruby-keyword">return</span> <span class="ruby-keyword">false</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-platform_errors">
              <b>platform_errors</b>()
            <a href="../../../classes/Hoodoo/Client/AugmentedBase.html#method-i-platform_errors" name="method-i-platform_errors" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>This call is typically used by external entities calling into a system via
<a href="../Client.html">Hoodoo::Client</a>.</p>

<p>Returns a <a href="../Errors.html">Hoodoo::Errors</a> instance that&#39;s
either been assigned via <a
href="AugmentedBase.html#method-i-set_platform_errors">set_platform_errors</a>
or is an empty, internally assigned collection. This method is very closely
related to <a
href="AugmentedBase.html#method-i-adds_errors_to-3F">adds_errors_to?</a>
and, if you have not already done so, you should read that method&#39;s
documentation before continuing.</p>

<p>For external client users, the error handling pattern is:</p>

<pre><code>client   = Hoodoo::Client.new( ... )
endpoint = client.resource( &#39;Foo&#39; )
result   = endpoint.show/list/create/update/delete( ... )

if result.platform_errors.halt_processing?
  # Handle result.platform_errors&#39;s error data
else
  # Success case
end</code></pre>

<p>For service authors, the <a
href="AugmentedBase.html#method-i-platform_errors">platform_errors</a>
method supports a slightly more verbose form of error handling for
inter-resource calls that avoids changing a passed in parameter in the
manner of <a
href="AugmentedBase.html#method-i-adds_errors_to-3F">adds_errors_to?</a>.
Compare the idiom shown there:</p>

<pre><code>return if list.adds_errors_to?( context.response.errors )
</code></pre>

<p>…with the idiomatic use of this method:</p>

<pre><code>context.response.add_errors( list.platform_errors )
return if context.response.halt_processing?
</code></pre>

<p>It is a little more verbose and very slightly less efficient as it involves
more method calls end to end, but you may prefer the conceptually cleaner
approach. You can lean on the return value of add_errors and end up back at
one line of (very slightly less obvious) code, too:</p>

<pre><code>return if context.response.add_errors( list.platform_errors )
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-platform_errors_source')" id="l_method-i-platform_errors_source">show</a>
              </p>
              <div id="method-i-platform_errors_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/augmented_base.rb, line 133</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">platform_errors</span>
  <span class="ruby-ivar">@nz_co_loyalty_platform_errors</span> <span class="ruby-operator">||=</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Errors</span>.<span class="ruby-identifier">new</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-set_platform_errors">
              <b>set_platform_errors</b>( errors )
            <a href="../../../classes/Hoodoo/Client/AugmentedBase.html#method-i-set_platform_errors" name="method-i-set_platform_errors" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Sets the <a href="../Errors.html">Hoodoo::Errors</a> instance used by <a
href="AugmentedBase.html#method-i-adds_errors_to-3F">adds_errors_to?</a> or
returned by <a
href="AugmentedBase.html#method-i-platform_errors">platform_errors</a>.</p>

<p>It is expected that only Hoodoo::Client-family code will call this method
as part of general error handling, though client code may find other uses
that are independent of the inter-resource call case wherein the method may
be safely invoked.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-set_platform_errors_source')" id="l_method-i-set_platform_errors_source">show</a>
              </p>
              <div id="method-i-set_platform_errors_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/augmented_base.rb, line 145</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">set_platform_errors</span>( <span class="ruby-identifier">errors</span> )
  <span class="ruby-ivar">@nz_co_loyalty_platform_errors</span> = <span class="ruby-identifier">errors</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
</div>

    </div>
  </body>
</html>
